---
sidebar_label: Scheduled Triggers
sidebar_position: 13
description: Manage Scheduled Triggers with the Hasura Metadata API
keywords:
  - hasura
  - docs
  - Metadata API
  - API reference
  - scheduled trigger
---

# Metadata API Reference: Scheduled Triggers

## Introduction

Scheduled Triggers are used to invoke webhooks based on a timestamp or
cron.

:::tip Supported from

The Metadata API is supported for versions `v2.0.0` and above and
replaces the older [schema/Metadata API](/api-reference/schema-metadata-api/index.mdx).

:::

## create_cron_trigger {#metadata-create-cron-trigger}

`create_cron_trigger` is used to create a new cron trigger.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "create_cron_trigger",
    "args" : {
        "name": "sample_cron",
        "webhook": "https://httpbin.org/post",
        "schedule":  "* * * * *",
        "payload": {
            "key1": "value1",
            "key2": "value2"
        },
        "include_in_metadata":false,
        "comment":"sample_cron comment"
    }
}
```

### Args syntax {#metadata-create-cron-trigger-syntax}

| Key                 | Required | Schema                                                                                                                               | Description                                                                                                                                                                                                     |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                | true     | [TriggerName](/api-reference/syntax-defs.mdx#triggername)                                                                            | Name of the cron trigger                                                                                                                                                                                        |
| webhook             | true     | [WebhookURL](/api-reference/syntax-defs.mdx#webhookurl)                                                                              | URL of the webhook                                                                                                                                                                                              |
| schedule            | true     | Cron Expression                                                                                                                      | Cron expression at which the trigger should be invoked.                                                                                                                                                         |
| payload             | false    | JSON                                                                                                                                 | Any JSON payload which will be sent when the webhook is invoked.                                                                                                                                                |
| headers             | false    | [[HeaderFromValue](/api-reference/syntax-defs.mdx#headerfromvalue) \| [HeaderFromEnv](/api-reference/syntax-defs.mdx#headerfromenv)] | List of headers to be sent with the webhook                                                                                                                                                                     |
| retry_conf          | false    | [RetryConfST](/api-reference/syntax-defs.mdx#retryconfst)                                                                            | Retry configuration if scheduled invocation delivery fails                                                                                                                                                      |
| include_in_metadata | true     | Boolean                                                                                                                              | Flag to indicate whether a trigger should be included in the metadata. When a cron trigger is included in the metadata, the user will be able to export it when the Metadata of the graphql-engine is exported. |
| comment             | false    | Text                                                                                                                                 | Custom comment.                                                                                                                                                                                                 |
| replace             | false    | Bool                                                                                                                                 | When replace is set to `true`, the cron trigger will be updated(if exists) and when it's `false` or the field is omitted, then a new cron trigger will be created.                                              |
| request_transform   | false    | [RequestTransformation](/api-reference/syntax-defs.mdx#requesttransformation)                                                        | Attaches a Request Transformation to the cron trigger.                                                                                                                                                          |
| response_transform  | false    | [ResponseTransformation](/api-reference/syntax-defs.mdx#responsetransformation)                                                      | Attaches a Request Transformation to the cron trigger.                                                                                                                                                          |

:::tip Supported from

Scheduled Triggers are supported from versions `v1.3.0` and above.

:::

## delete_cron_trigger {#metadata-delete-cron-trigger}

`delete_cron_trigger` is used to delete an existing cron trigger. The
scheduled events associated with the cron trigger will also be deleted.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "delete_cron_trigger",
    "args" : {
        "name": "sample_cron"
    }
}
```

### Args syntax {#metadata-delete-cron-trigger-syntax}

| Key  | Required | Schema                                                    | Description              |
| ---- | -------- | --------------------------------------------------------- | ------------------------ |
| name | true     | [TriggerName](/api-reference/syntax-defs.mdx#triggername) | Name of the cron trigger |

:::tip Supported from

Scheduled Triggers are supported from versions `v1.3.0` and above.

:::

## create_scheduled_event {#metadata-create-scheduled-event}

`create_scheduled_event` is used to create a scheduled event.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "create_scheduled_event",
    "args": {
        "webhook": "https://httpbin.org/post",
        "schedule_at": "2019-09-09T22:00:00Z",
        "payload": {
            "key1": "value1",
            "key2": "value2"
        },
        "headers": [{
            "name":"header-key",
            "value":"header-value"
        }],
        "comment": "sample scheduled event comment"
    }
}
```

Upon creating a scheduled event successfully, this API will return the
`event_id` in the response.

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "success",
    "event_id": "b918cd10-8853-4e66-91b8-81b5cd16e44b"
}
```

### Args syntax {#metadata-create-scheduled-event-syntax}

| Key         | Required | Schema                                                                                                                               | Description                                                      |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| webhook     | true     | [WebhookURL](/api-reference/syntax-defs.mdx#webhookurl)                                                                              | URL of the webhook                                               |
| schedule_at | true     | Timestamp (ISO8601 format)                                                                                                           | The time at which the invocation should be invoked.              |
| payload     | false    | JSON                                                                                                                                 | Any JSON payload which will be sent when the webhook is invoked. |
| headers     | false    | [[HeaderFromValue](/api-reference/syntax-defs.mdx#headerfromvalue) \| [HeaderFromEnv](/api-reference/syntax-defs.mdx#headerfromenv)] | List of headers to be sent with the webhook                      |
| retry_conf  | false    | [RetryConfST](/api-reference/syntax-defs.mdx#retryconfst)                                                                            | Retry configuration if scheduled event delivery fails            |
| comment     | false    | Text                                                                                                                                 | Custom comment.                                                  |

:::tip Supported from

Scheduled Triggers are supported from versions `v1.3.0` and above.

:::

## delete_scheduled_event {#metadata-delete-scheduled-event}

`delete_scheduled_event` is used to delete an existing scheduled event
(one-off or cron).

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "delete_scheduled_event",
    "args" : {
        "type": "one_off",
        "event_id": "b918cd10-8853-4e66-91b8-81b5cd16e44b"
    }
}
```

### Args syntax {#metadata-delete-scheduled-event-syntax}

| Key      | Required | Schema              | Description                      |
| -------- | -------- | ------------------- | -------------------------------- |
| type     | true     | `one_off` \| `cron` | Type of the Event Trigger.       |
| event_id | true     | UUID                | The `id` of the scheduled event. |

:::tip Supported from

Scheduled Triggers are supported from versions `v1.3.0` and above.

:::

## get_cron_triggers {#metadata-get-cron-triggers}

`get_cron_triggers` fetches all the cron triggers from the metadata.
This API also returns the cron triggers which have `include_in_metadata`
set to `false`, and thus are not exported in the `export_metadata` API.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "get_cron_triggers",
    "args" : {}
}
```

## get_scheduled_events {#metadata-get-scheduled-events}

`get_scheduled_events` provides a way to retrieve cron/one-off scheduled
events present in the graphql-engine.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "get_scheduled_events",
    "args" : {
      "type": "cron",
      "trigger_name": "daily_trigger",
      "limit": 10,
      "offset": 0,
      "status": [
        "scheduled",
        "delivered"
      ],
      "get_rows_count": false
    }
}
```

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "get_scheduled_events",
    "args" : {
      "type": "one_off",
      "limit": 10,
      "offset": 0,
      "get_rows_count": true
    }
}
```

### Args Syntax {#metadata-get-scheduled-events-syntax}

| Key            | Required                   | Schema                                                                        | Description                                                                          |
| -------------- | -------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| type           | true                       | `one_off` \| `cron`                                                           | Type of the Scheduled Trigger.                                                       |
| trigger_name   | only when `type` is `cron` | String                                                                        | Name of the cron trigger                                                             |
| limit          | false                      | Integer                                                                       | Maximum number of events to be returned in one API call.                             |
| offset         | false                      | Integer                                                                       | Starting point from where the rows need to be returned.                              |
| get_rows_count | false                      | Boolean                                                                       | Flag to indicate whether number of rows returned should be included in the response. |
| status         | false                      | [[ScheduledEventStatus]](/api-reference/syntax-defs.mdx#scheduledEventStatus) | Filter scheduled events by the status                                                |

## get_scheduled_event_invocations {#metadata-get-scheduled-event-invocations}

`get_scheduled_event_invocations` provides a way to retrieve the scheduled
event invocations of a specific scheduled event or a cron trigger.

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "get_scheduled_event_invocations",
    "args": {
        "type": "cron",
        "trigger_name": "daily_trigger",
        "limit": 10,
        "offset": 0
    }
}
```

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type" : "get_scheduled_event_invocations",
    "args" : {
      "type": "one_off",
      "limit": 10,
      "offset": 0,
      "get_rows_count": true
    }
}
```

### Args Syntax {#metadata-get-scheduled-event-invocations-syntax}

| Key            | Required                   | Schema              | Description                                                                          |
| -------------- | -------------------------- | ------------------- | ------------------------------------------------------------------------------------ |
| type           | true                       | `one_off` \| `cron` | Type of the Scheduled Trigger.                                                       |
| trigger_name   | only when `type` is `cron` | String              | Name of the cron trigger                                                             |
| event_id       | false                      | String              | Getting invocations of the specified event                                           |
| limit          | false                      | Integer             | Maximum number of events to be returned in one API call.                             |
| offset         | false                      | Integer             | Starting point from where the rows need to be returned.                              |
| get_rows_count | false                      | Boolean             | Flag to indicate whether number of rows returned should be included in the response. |
